﻿#region Copyright & License
//
// Project: Quark Framework
// Project site: http://quark.codeplex.com
// See the copyright statement on the project site for more details.
//
// Licensed to the Apache Software Foundation (ASF) under one or more 
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership. 
// The ASF licenses this file to you under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with 
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Quark.Framework.Exceptions;

namespace Quark.Framework
{
    /// <summary>
    /// 表示对象实例需要在容器中运行的接口
    /// </summary>
    /// <remarks>
    /// <list type=" number">
    /// <listheader>
    /// <term>创建对象实例后，其所实现的接口在容器中被调用顺序依次为：</term>
    /// </listheader>
    /// <item>
    /// <term><see cref="IInitializable.InitializeInstance()"/></term>
    /// <description>初始化对象实例</description>
    /// </item>
    /// <item>
    /// <term><see cref="IContextualizable.Contextualize(IQuarkContext)"/></term>
    /// <description>将对象实例置入上下文环境</description>
    /// </item>
    /// <item>
    /// <term><see cref="IConfigurable.Configure(IConfiguration)"/></term>
    /// <description>初始化对象实例的配置</description>
    /// </item>
    /// <item>
    /// <term><see cref="IStartable.StartRun()"/></term>
    /// <description>启动对象实例</description>
    /// </item>
    /// </list>
    /// </remarks>
    public interface IContextualizable
    {
        /// <summary>
        /// 当前对象实例置入上下文环境
        /// </summary>
        /// <param name="context">上下文环境实例</param>
        /// <exception cref="ArgumentNullException"><paramref name="context"/>参数为空值</exception>
        /// <exception cref="InvokeOnceException">该方法在同一个对象实例上被调用多次引发此异常</exception>
        /// <exception cref="ContextualizeException">置入上下文发生异常，内部抛出的异常统一以<see cref="ContextualizeException"/>作为异常封装</exception>
        /// <invokeonce/>
        /// <serialization/>
        void Contextualize(IQuarkContext context);
    }

    /// <summary>
    /// 本接口是<see cref="IContextualizable"/>接口的泛型版本
    /// </summary>
    /// <typeparam name="TContext">上下文类型</typeparam>
    public interface IContextualizable<TContext> : IContextualizable
        where TContext : class, IQuarkContext
    {
        /// <summary>
        /// 当前对象实例置入上下文环境
        /// </summary>
        /// <param name="context">上下文环境实例</param>
        /// <exception cref="ArgumentNullException"><paramref name="context"/>参数为空值</exception>
        /// <exception cref="InvokeOnceException">该方法在同一个对象实例上被调用多次引发此异常</exception>
        /// <exception cref="ContextualizeException">置入上下文发生异常，内部抛出的异常统一以<see cref="ContextualizeException"/>作为异常封装</exception>
        /// <invokeonce/>
        /// <serialization/>
        void Contextualize(TContext context);
    }
}
